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Chapter 1 


Application Launcher Foundation API 


1.1 References 
[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 


[2] Security Policy Enforcement Framework (SPEF) Foundation API, Version 1.0, LiMo Foundation, 1 
February 2008 


1.2 Overview 


Application Launcher is responsible for application launch, maintenance of application runtime informa- 
tion and maintenance of application life cycle. Applications should be launched by Application Launcher. 
When the Application Launcher launches an application instance, it adds the information of the applica- 
tion instance to the runtime information table. The runtime information includes application program id, 
instance id, process id and application state. 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


1.5 Plug-in Extension Point Interface 


None 


Application Launcher Foundation API 


1.6 Other Interfaces 


None 


1.7 Other Notes 


None 
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Chapter 2 


Module Index 


2.1 Modules 


Here is a list of all modules: 


Application Launcher 


Application Launcher Code Examples .......... o... o... e... 


Module Index 
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Chapter 3 


Class Index 


3.1 Class List 


Here are the classes, structs, unions and interfaces with brief descriptions: 


EPPNETAPpome o. oido a ee a an ee ee RE AA 


Class Index 
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Chapter 4 


File Index 


4.1 File List 


Here is a list of all documented files with brief descriptions: 


ComponentOverview.h (Component Programming Interface Overview Header Template for 
Dn A a Shee Eo hake OER a 


File Index 
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Chapter 5 


Module Documentation 


5.1 Application Launcher 


Classes 


e struct AppMgrAppState_t 


Application Attribute types 


e enum AppMgrAppAttribute_t | MIME_TYPE, FILE_EXTENSION, SERVICE_NAME } 


Exit code(s) 


e #define APPMGR_APP_ABNORMAL_ TERMINATION -1 


Application Launcher Error codes 


#define APPMGR_ERROR_UNKNOWN -7 

#define APPMGR_ERROR_INVALID_ID -8 

#define APPMGR_ERROR_LAUNCH_FAILURE -9 

#define APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR -10 
#define APPMGR_ERROR_ALREADY_RUNNING -11 

#define APPMGR_ERROR_INVALID_INSTANCE_ID -15 

#define APPMGR_ERROR_INVALID_ATTRIBUTE -16 

#define APPMGR_ERROR_INVALID_PID -17 


Application Model Error codes 


e #define APPMGR_ERROR_MODEL_NOT_FOUND -13 
e #define APPMGR_ERROR_CANNOT_INIT_PLUGIN -14 
e #define APPMGR_ERROR_ALREADY_LOADED_PLUGIN -12 


10 Module Documentation 


Defines 


. #define APPMGR_APP_PATH_LEN_MAX (256) 
< #define APPMGR_APP_ARG LEN_MAX (1024) 
< #define APPMGR_APP_UNIQUE_ID_LEN_MAX (4) 


Typedefs 


e typedef int AppMgrAppUniqueld_t [APPMGR_APP_UNIQUE_ID_LEN_MAX] 
e typedef int(x AppMgrAppGetCurrentldFn_t )(int x) 
e typedef int(x AppMgrAppGetCurrentInstldFn_t )(int x) 


Functions 


e int AppMerAppLaunch (int app_id, const char *param, void *app_model_data, int *inst_id) 


int AppMgrAppAttributeLaunch (int type, const char xattribute, const char «param, int xinst_id) 
int AppMerAppKill (int inst_id) 
int AppMgrAppCommand (int inst_id, int command, char xdata) 


int AppMgrAppGetRunningApps (int xapps, int *num_returned) 


int AppMgrAppGetRunningInstances (int app_id, int xinst_ids, int «num_returned) 


int AppMgrAppGetRunningInstancesInPid (pid_t pid, int *inst_ids, int *num_returned) 


int AppMgrApplsRunning (int app_id) 


int AppMerAppGetInstInfo (int inst_id, int xapp_id, pid_t *pid) 
int AppMgrAppGetState (int inst_id, AppMgrAppState_t xstate) 
int AppMgrAppGetUniqueld (int app_id, AppMgrAppUniqueld_t xunique_id) 


int AppMgrAppGetCurrentld (int xapp_id) 
int AppMgrAppGetCurrentlInstld (int *inst_id) 


5.1.1 Define Documentation 
5.1.1.1 #define APPMGR_APP_ABNORMAL_TERMINATION -1 


This code indicates abnormal termination of an application. 


5.1.1.2 #define APPMGR_ERROR_ALREADY_LOADED_PLUGIN -12 


This error code indicates that the Application Launcher is trying to load a plugin that was loaded already. 


5.1.1.3 #define APPMGR_ERROR_ALREADY_RUNNING -11 


This error code indicates that the application is already running and multi-instance is not allowed. 


5.1.1.4 #define APPMGR_ERROR_CANNOT_INIT_PLUGIN -14 


This error code indicates that Applciation Launcher encountered errors while initializing the plugin. 
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5.1.1.5 #define APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR -10 


This error code indicates that an error was returned by the internal IPC mechanism. 


5.1.1.6 #define APPMGR_ERROR_INVALID_ATTRIBUTE -16 


This error code indicates that a request to launch an application based on the attribute passed is not sup- 
ported. 


5.1.1.7 #define APPMGR_ERROR_INVALID_ID -8 


This error code indicates that the application program id does not exist in the system. 


5.1.1.8 #define APPMGR_ERROR_INVALID_INSTANCE_ID -15 


This error code indicates that the instance id cannot be found in application running list. 


5.1.1.9 #define APPMGR_ERROR_INVALID_PID -17 


This error code is returned when no process with the pid was not found to be running. 


5.1.1.10 #define APPMGR_ERROR_LAUNCH_FAILURE -9 


This error code indicates that the application could not be launched properly. 


5.1.1.11 #define APPMGR_ERROR_MODEL_NOT_FOUND -13 


This error code indicates that the app’s model type could not be mapped to any of the loaded plug-ins. 


5.1.1.12 #define APPMGR_ERROR_UNKNOWN -7 


This error code indicates the unknown error. 


5.1.2 Typedef Documentation 
5.1.2.1 typedef int(x AppMgrAppGetCurrentldFn_t)(int <) 


A Type of function the plugin must implement. The app launcher uses this implemented function to retrieve 
the application program id in whose context the AppMgrAppGetCurrentld() is called. 


5.1.2.2 typedef int(+ AppMgrAppGetCurrentInstIdFn_t)(int x) 


A Type of function the plugin must implement. The app launcher uses this implemented function to retrieve 
the application instance id in whose context the AppMgrAppGetCurrentInstld() is called. 
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5.1.3 Enumeration Type Documentation 


5.1.3.1 enum AppMgrAppAttribute_t 


Enumerator: 
MIME_TYPE This code is used to launch an application in accordance with its MIME type. 
FILE_EXTENSION This code is used to launch an application in accordance with its file extension. 


SERVICE_NAME This code is used to launch an application in accordance with its service name. 


5.1.4 Function Documentation 


5.1.4.1 int AppMgrAppAttributeLaunch (int type, const char * attribute, const char * param, int x 
inst_id) 


This API launches the application in accordance with the MIME type of the content, file extension, by 
service name and by full application name. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 
[IN] type Specifies the attribute type based on which the launching is to be done. 
[IN] attribute Specifies the value of the attribute type passed in the type” argument. 


[IN] param Specifies the parameter passed to the application. The length of parameter should be less 
than 1024. NULL if there is no parameter. 


[OUT] inst_id Application instance id 


Returns: 


This API returns O on success or error-code on failure. 


Exceptions: 
APPMGR_ERROR_INVALID_ATTRIBUTE 
APPMGR_ERROR_LAUNCH_FAILURE 
APPMGR_ERROR_ALREADY_RUNNING 
APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


Remarks: 


It posts a "LiMo.System.AL.Launch" event on successful launch of application. This event is asyn- 
chronous and has the following properties, 


application program id(app_id) : integer; 


app instance id(inst_id) : integer 
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5.1.4.2 int AppMgrAppCommand (int inst_id, int command, char x data) 


This API commands the Application Model plugin to do something to an application or to get the applica- 
tion to do something. 


Sync (or) Async: 


This is aSynchronous API. 


Parameters: 
[IN] inst_id Specifies the application instance on which the command is to be executed. 
[IN] command Specifies the command to be handled. 


[IN] data Specifies the data required to handle the command if any. 


Returns: 


This API returns 0 on success or error-code on failure. 


Exceptions: 
APPMGR_ERROR_INVALID_INSTANCE_ID 
APPMGR_ERROR_MODEL_NOT_FOUND 
APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


Remarks: 


The application launcher does not know what the command means. It is the Application model that 
defines and processes the command. 


5.1.4.3 int AppMgrAppGetCurrentld (int < app_id) 


This function returns the application program id of the application instance in whose context this call is 
made. This function only invokes the function of type AppMgrAppGetCurrentldFn_t implemented by 
plugin corresponding to the application model type. It is the responsibility of the plugin to retrieve the 
application program id. 


Sync (or) Async: 


This is aSynchronous API. 


Parameters: 


[OUT] app_id Specifies the application program id returned 


Returns: 


This API returns O on success or error-code on failure. 
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5.1.4.4 int AppMgrAppGetCurrentInstld (int x inst_id) 
This API returns the instance ID of the application instance in whose context this call is made. This function 
only invokes the function of type AppMgrAppGetCurrentInstIdFn_t implemented by plugin corresponding 
to the application model type. It is the responsibility of the plugin to retrieve the application instance id. 
Sync (or) Async: 

This is aSynchronous API. 


Parameters: 


[OUT] inst_id Specifies the instance ID returned. 


Returns: 


This API returns O on success or error-code on failure. 


5.1.4.5 int AppMgrAppGetInstInfo (int inst_id, int < app_id, pid_t x pid) 
This API returns the application instance information. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] inst_id Specifies the application instance. 
[OUT] app_id Specifies the application program id of the instance. 
[OUT] pid Specifies the process ID of the instance. 


Returns: 


This API returns O on success or error-code on failure. 


Exceptions: 


APPMGR_ERROR_INVALID_INSTANCE_ID,APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


5.1.4.6 int AppMgrAppGetRunningApps (int « apps, int x num_returned) 
This API returns the application program ids of applications running. 
Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[OUT] apps Specifies the pointer to the application program id array. 


[OUT] num_returned Specifies the number of running application program ids returned. 
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Returns: 


This API returns O on success or error-code on failure. 


Exceptions: 


APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


Remarks: 


The Application Launcher allocates memory to hold the information. It is the responsibilty of the 
caller (the application) to free the memory AL allocated after use. 


5.1.4.7 int AppMgrAppGetRunningInstances (int app_id, int x inst_ids, int x num_returned) 


This API returns the instance ids of the running instances of an application . 


Sync (or) Async: 


This is aSynchronous API. 


Parameters: 
[IN] app_id Specifies the application program id whose instances are returned. 
[OUT] inst_ids Specifies the pointer to the application instance id array. 


[OUT] num_returned Specifies the number of instances returned. 


Returns: 


This API returns O on success or error-code on failure. 


Exceptions: 


APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR,APPMGR_ERROR_INVALID_ID 


Remarks: 


The Application Launcher allocates memory to hold the information. It is also the responsibilty of the 
caller (the application) to free the memory AL allocated after use. 


5.1.4.8 int AppMgrAppGetRunningInstancesInPid (pid_t pid, int x inst_ids, int x num_returned) 
This API returns the application instances running in a process. 


Sync (or) Async: 


This is aSynchronous API. 


Parameters: 
[IN] pid Specifies the process id. 
[OUT] inst_ids Specifies the pointer to the array of instance ids . 


[OUT] num_returned Specifies the number of application instance ids returned. 
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Returns: 


This API returns O on success or error-code on failure. 
Exceptions: 
APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR,APPMGR_ERROR_INVALID_PID 


Remarks: 


The Application Launcher allocates memory to hold the information. It is also the responsibilty of the 
caller (the application) to free the memory AL allocated after use. 


5.1.4.9 int AppMgrAppGetState (int inst_id, AppMgrAppState_t x state) 


This API gets the state of the application. 
Sync (or) Async: 
This is aSynchronous API. 


Parameters: 


[IN] inst_id Specifies the application instance ID. 
[OUT] state Specifies the application state returned. 


Returns: 
This API returns O on success or error-code on failure. 
Exceptions: 


APPMGR_ERROR_INVALID_INSTANCE_ID,APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


Remarks: 


The application states are opaque to the Application launcher. 


5.1.4.10 int AppMgrAppGetUniqueld (int app_id, AppMgrAppUniqueld_t x unique_id) 


This API returns the application unique id of the application instance. 
Sync (or) Async: 
This is aSynchronous API. 


Parameters: 


[IN] app_id Specifies the application program ID. 
[OUT] unique_id Specifies the application unique id. 


Returns: 
This API returns O on success or error-code on failure. 
Exceptions: 


APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR,APPMGR_ERROR_INVALID_ID 
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5.1.4.11 int AppMgrApplsRunning (int app_id) 
This API returns whether the application is running or not. 
Sync (or) Async: 

This is aSynchronous API. 


Parameters: 


[IN] app_id Specifies the application program id. 
Returns: 


This API returns 0 if the application is running or error-code on failure. 


Exceptions: 


APPMGR_ERROR_INVALID_ID,APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


5.1.4.12 int AppMgrAppKill (int inst_id) 
This API terminates the application. 
Sync (or) Async: 

This is aSynchronous API. 


Parameters: 


[IN] inst_id Specifies the application instance to be terminated. 
Returns: 

This API returns 0 on success or error-code on failure. 
Exceptions: 


APPMGR_ERROR_INVALID_INSTANCE_ID 
APPMGR_ERROR_MODEL_NOT_FOUND 
APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


5.1.4.13 int AppMgrAppLaunch (int app_id, const char + param, void < app_model_data, int * 
inst_id) 


This API starts an application, given its application program id . 
Sync (or) Async: 
This is aSynchronous API. 


Parameters: 


[IN] app_id Specifies the application program id. The application has to be installed before being 
launched, on which it gets its application program id. 
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[IN] param Specifies the parameter passed to the application. The length of parameter should be less 
than 1024. NULL if there is no parameter. 


[IN] app_model_data Data(if any)to be sent to the plugin corresponding to the applications’s model. 
[OUT] inst_id Application instance id 


Returns: 


This API returns O on success or error-code on failure. 


Exceptions: 


APPMGR_ERROR_INVALID_ID 
APPMGR_ERROR_LAUNCH_FAILURE 
APPMGR_ERROR_ALREADY_RUNNING 
APPMGR_ERROR_INTERNAL_TRANSPORT_ERROR 


Remarks: 


It posts a "LiMo.System.AL.Launch" event on successful launch of application. This event is asyn- 
chronous and has the following properties, 


application program id of the application launched(app_id) : integer 


app instance id of the application launched(inst_id) : integer 
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5.2 Application Launcher Code Examples 


An application can be launched using AppMgrAppLaunch(). The AppMgrAppLaunch() requires the ap- 
plication program id. The AppMgrAppLaunch() allows a string parameter to be passed as the argument. It 
also allows data(if any) to be sent to the plug-in corresponding to the application model. It returns an appli- 
cation instance id for the application that was launched. Following code snippet shows a sample application 
using AppMgrAppLaunch(). 


int app_id; 

int inst_id, 

int ret; 

char param[] = "MYAPP"; 


app_id = 6000; 

ret = AppMgrAppLaunch (app_id, param, NULL, &inst_id) ; 

if (ret != 0) 

{ 
fprintf(stderr, "AppMgrAppLaunch() failed.\n"); 
fprintf(stderr, "error_code : %d.\n", ret); 
return; 


} 
// do something 


return; 


Application Launcher keeps the list of running applications. The application program ids of apps currently 
running can be obtained using AppMgrAppGetRunningApps(). 


int x*apps; 
int num_returned; 
int ret; 


//Memory for 'apps’ will be allocated by Application Launcher and freed by the caller application. 


ret = AppMgrAppGetRunningApps (apps, &num_returned) ; 

if (ret != 0) 

{ 
fprintf(stderr, "AppMgrAppGetRunningApps() failed.\n"); 
fprintf(stderr, "error_code : %d.\n", ret); 
return; 


} 

// do something 

// Application must free apps 
if (apps != NULL) 


free (apps); 


return; 
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Class Documentation 


6.1 AppMgrAppState_t Struct Reference 


#include <app-manager.h> 


6.1.1 Detailed Description 


This structure holds the state of an application. 


Public Attributes 


e int state 
The documentation for this struct was generated from the following file: 


* app-manager.h 
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File Documentation 


7.1 ComponentOverview.h File Reference 


7.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 
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